Skip to content

feat: PDF 图形工具箱(需 Android 真机测试) - #231

Merged
greyoak111 merged 3 commits into
greyoak111:mainfrom
fisHarly0:feat/pdf-toolbox
Nov 18, 2026
Merged

greyoak111 merged 3 commits into
greyoak111:mainfrom
fisHarly0:feat/pdf-toolbox

Conversation

@fisHarly0

@fisHarly0 fisHarly0 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

改了什么、为什么 / What and why

现有 pdf-tools 组件已经能处理 PDF,但主要通过命令行使用。这次给文件面板和 PDF 查看器补了一个图形入口,选好文件后就能处理,不需要经过聊天或消耗模型额度。

  • 合并 PDF,并调整合并顺序。
  • 按 1-3,5 这样的页码提取页面、拆成单页,或旋转指定页面。
  • 通过已有 pdf-shrink 压缩;结果没有变小时明确提示。
  • 转成 PNG / JPEG,支持选择页码和分辨率。
  • 后台处理、取消、错误后重试,以及通过现有查看器打开结果、分享和前往结果目录。
  • 复用已有 qpdf / Poppler / Ghostscript、文件路径限制及子进程标记,不增加依赖或构建步骤,不改 PDF.js。

输出写到新文件夹,不覆盖原件;一次只跑一个任务,并设置输入、输出、页数、时间和磁盘余量限制。使用说明见 docs/pdf-tools.zh-CN.md。

这次改动范围比较大,先以草稿 PR 给出一个可讨论的实现,想请你看看这样的入口和范围是否适合项目;如果希望先讨论或拆小,也可以再调整。

怎么测的 / How it was tested

⚠️ 需要本地 Android 真机测试,当前尚未完成

我这边目前不方便进行 Android 真机测试,因此还没有在实际机型上安装测试包,也没有可报告的 Android 机型/系统版本实测结果。知道贡献指南要求真机验证,所以先标为 Draft,请不要把下面的桌面验证视为 Android 验收或可直接合并的依据。

如果这个方向合适,希望能请你或有条件的朋友在本地真机上验证,再决定是否继续推进或合并。

已完成的桌面验证:

  • Windows 下使用隔离测试目录;针对现有 Android/Linux 模块,测试进程中临时补了 getuid/geteuid 并归一化源码文本换行,这些适配没有提交到产品。
  • 选定回归覆盖组件界面、语言词典和文件查看器;本轮 PDF 单元检查 7 项通过,其中 2 项直接验证解析器环境隔离和 Android 加载器变量。Linux CLI fixture 在 Windows 明确跳过 1 项。
  • 真实 PDF 文件检查:合并/提取页序、拆分页内容、指定页旋转角度、PNG/JPEG 输出、压缩结果可读性、原件逐字节不变;另检查了目录冲突、取消/互斥、损坏和加密输入、输入超限,以及写盘失败时保留用户修改过的结果。
  • 原生工具为 qpdf 12.4.2、Poppler 26.07.0 和 Ghostscript 10.08.0。压缩的 Windows 验证适配器使用原 pdf-shrink 相同的 Ghostscript 参数,尚未验证 Android 的 shell 包装与 exec 垫片;Android 配方中的 Poppler 版本也不同。
  • Microsoft Edge 157.0.4341.60,1366×900 / 390×844:文件选择、多选排序、真实合并、页码错误与重试、结果在 PDF.js 打开、文件输入导入、预览往返和缺组件提示等 13 组检查通过,最终脚本异常 0。PDF/文件/鉴权路由使用真实实现,其余账号和设备接口使用隔离 fixture。
  • 前后端语法、翻译覆盖和差异检查通过;仓库 PR 安全初筛为高 0、中 2(必要的子进程调用,以及纯数据测试中的假代理地址 fake.invalid;测试不会连接该地址)。尚未完成独立审查。

仍需在 Android 本地验证:

  • 安装 CI 测试包,记录机型及 Android 版本;不要卸载有重要数据的正式版来替换,优先使用测试设备。

  • 安装 pdf-tools,确认 qpdf、pdftoppm、pdf-shrink 和基础 Ghostscript 经实际运行环境能启动。

  • 合并、提取、拆分、旋转、压缩、PNG/JPEG 输出及结果预览。

  • Android 系统文件选择、文件访问权限及系统分享。

  • 长任务取消、后台切换、空间不足与失败后的清理;确认原件不变。

  • 新的界面文案都走了 t() 并补了译文 / New UI strings use t() and have translations

  • 没有引入新依赖或构建步骤 / No new dependencies or build steps

  • 没有二进制、压缩或混淆过的代码;未改第三方代码 / No binaries, minified or obfuscated code; no third-party code changes

安全初筛后补充核对

已逐项审计 bot 标记的子进程和测试环境变量使用:

  • 处理程序和参数走 argv;Linux shell 的程序段固定为 exec "$0" "$@",并显式使用 shell: false,文件路径不会拼进 shell 源码。
  • PDF 处理直接构造最小环境,去掉对终端环境函数的调用,不为文档处理触发终端的密钥辅助文件流程;CCAPP_GLIBC_* 改为明确变量名单,假造的 CCAPP_GLIBC_API_KEY 等不再透传。
  • 对照 Env.java / exec-shim.c,保留加载器所需的三项 TERMUX_* 变量和 bionic preload;新增纯数据回归覆盖这一契约。Android 实际加载器行为仍在真机待测清单中。
  • 凭据过滤用传入函数的假对象验证,不再修改测试进程中的密钥类环境变量。假代理地址只用作输入数据,没有网络请求。
  • 改动后相关单元检查 7 项通过、Windows 真实 PDF 的 11 组处理/失败路径回归通过。仍保持 Draft,未将桌面结果当作 Android 验收。

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

PR 安全初筛 / Safety pre-check

改动 26 个文件;高 0 项、中 2 项。

档 文件 行 为什么要看
中 gateway/gw/pdf-tools.mjs 4 起子进程
中 gateway/tests/pdf-tools.test.mjs 58 新出现的外部域名 fake.invalid

「高」不等于有问题,只是这些地方一旦被动手脚,后果最重(能拿到签名钥匙、改到用户手机上的权限、或藏进看不见的内容),合并前请逐行看过。

@greyoak111

Copy link
Copy Markdown
Owner

emmmm,我后续有时间了就来琢磨一下具体的处理方案,感谢提出pr。

@fisHarly0

Copy link
Copy Markdown
Contributor Author

okk,主要是看到之前的对pdf那些的处理感觉不够整合,做了个这个,能有帮助当然更好,没帮助也没关系啦,感谢回应

@greyoak111

Copy link
Copy Markdown
Owner

真机冒烟发现一个小问题:转图片的 DPI 选项被 -scale-to 2048 完全抵消了。

pdftoppm 的 -scale-to 是「缩放进 2048² 框」(含放大),不是「只缩不放」。于是任何页面的栅格都会贴到 2048 长边:

  • 12×16cm 页面,-r 72 直出是 340×453(11,404 字节);
  • 经模块 72 DPI → 1536×2048(58,680 字节);
  • 经模块 150 DPI → 同样 1536×2048,58,680 字节——两档产物逐字节同尺寸。

也就是说「低(72 DPI)/ 清晰(150 DPI)」两档在所有常见页面尺寸下输出完全相同,低档反而比真正的 72 DPI 大 5 倍,与界面标签和使用文档(72/150 DPI)不符。

建议修法:先 pdfinfo 取页面最大尺寸(pt),按 dpi 算出栅格长边,只在超过 2048 时才追加 -scale-to 2048(防巨幅页面的初衷保留),平时不加。改动约几行。

其余六种操作(合并/提取/拆分/旋转/压缩/转图)都用真 qpdf/pdf-shrink/gs/pdftoppm 冒烟过了,结果正确;注入、私密路径、坏文件拒绝也验证无误。

@greyoak111

Copy link
Copy Markdown
Owner

这个问题维护者已在本地 main 修复(提交 f1188f5,尚未推送):转图片先用 pdfinfo 按所选分辨率算栅格长边,超过 2048 才加 -scale-to,解析不到时保守封顶;补了 pdfImageCap 单测。真工具复测:72 DPI 11404 字节(341×454)、150 DPI 24126 字节(709×945),巨幅页仍封顶 2048×2048。作者无需重复处理。

@greyoak111
greyoak111 merged commit 5e9feef into greyoak111:main Nov 18, 2026
3 checks passed

This branch was successfully deployed

1 active deployment
apk-ci — ff8dbb43 Deployed Nov 17, 2026 by fisHarly0 via build #260
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants